gh-102249: Expand sys.call_tracing documentation #102806
Conversation
impact27
commented
Mar 18, 2023
•
impact27
commented
- Issue: cProfile does not work in pdb #102249
impact27
changed the title
hugovk
changed the title
CAM-Gerlach
added
needs backport to 3.10
|
(Removed the Fixes tag since we only close the associated issue when all backport PRs are merged, as is SOP for docs changes like this). |
There was a problem hiding this comment.
Standard reminder: You can directly apply all the suggestions you want in one go with Files changed -> Add to batch -> Commit
Don''t we also want to add a note in the setprofile and settrace descriptions referring readers to call_tracing to nest tracing/profiling an existing tracing/profiling session, to properly address the original issue that prompted the issue? Otherwise, readers may try to use these together anyway and not find call_tracing on their own right way, no?
I suggest adding a .. note:: with similar or somewhat more cut down version of the text here to each at the end of the main top-level description (before getting in to the event details).
Co-authored-by: C.A.M. Gerlach <[email protected]>
Doc/library/sys.rst
Outdated
| @@ -1415,6 +1419,11 @@ always available. | |||
| ``'c_exception'`` | |||
| A C function has raised an exception. *arg* is the C function object. | |||
|
|
|||
| .. note:: | |||
There was a problem hiding this comment.
I can't reach it with a comment, but after applying the suggested changes, I recommend moving this note above the list of events to be more consistent with the other added note and avoid getting lost there. Specifically, I suggest swapping it with the audit-event directive, which would be consistent with how both are in settrace and also avoids obvious confusion (which confused me, certainly) between the event argument and the audit event, given the latter is currently the one mentioned immediately before "the events have the following meaning" which confusing implies it is being referred to there, rather than the events discussed in the paragraph above the audit-event directive.
Co-authored-by: C.A.M. Gerlach <[email protected]>
Doc/library/sys.rst
Outdated
| .. note:: | ||
| The same tracing mechanism is used for :func:`!setprofile` as :func:`settrace`. | ||
| To trace calls with :func:`!setprofile` inside a tracing function (e.g. in a | ||
| debugger breakpoint) see :func:`call_tracing`. | ||
|
|
||
| .. audit-event:: sys.setprofile "" sys.setprofile |
There was a problem hiding this comment.
Hey, sorry if I was unclear before—the note should go one block above, and the audit-event should go where the `note used to be (i.e. below the list of event values. This will avoid interjecting these two between the introduction of the profile function args and the description of their values, which is particularly confusing to readers because the audit "events" are entirely unrelated to the event argument here.
Also, the indents got off as a result of this change.
As I should have before, here's a patch you can apply with
git apply 0001-Move-call_tracing-note-audit-event-in-setprofile-to-.patchto fix all this directly:
0001-Move-call_tracing-note-audit-event-in-setprofile-to-.patch
|
All commit authors signed the Contributor License Agreement. |
(cherry picked from commit 2445673) Co-authored-by: Quentin Peter <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
(cherry picked from commit 2445673) Co-authored-by: Quentin Peter <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
|
GH-111557 is a backport of this pull request to the 3.12 branch. |
|
GH-111558 is a backport of this pull request to the 3.11 branch. |
…111557) Co-authored-by: Quentin Peter <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
…111558) Co-authored-by: Quentin Peter <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
